Skip to content

fix: keep chapter descriptions after hydration - #41

Merged
mokevnin merged 1 commit into
mainfrom
fix/seo-descriptions
Nov 21, 2026
Merged

mokevnin merged 1 commit into
mainfrom
fix/seo-descriptions

Conversation

@mokevnin

Copy link
Copy Markdown
Owner

Problem

  • After hydration, the VitePress client rewrote <meta name="description"> to the page's frontmatter description. That field was empty, so it fell back to the site description, and every rendered page showed the same English sentence. Crawlers that run JS (Google does) saw that sentence instead of the chapter's text.
  • VitePress keeps one meta per key, so only the last og:locale:alternate tag survived.
  • The three table-of-contents pages (SUMMARY.html) had an empty description.

Changes

  • A markdown-it plugin in book/.vitepress/seo.mjs writes each page's description into its frontmatter while the page renders. The SSR HTML, the client and og:description now share that one value. A hand-written description: in frontmatter still wins.
  • A table-of-contents page takes the description of its locale's home page.
  • Each og:locale:alternate tag gets its own id.
  • AGENTS.md documents both rules.

Verification

  • Every page's description is the same as before, except the three SUMMARY pages, which now have one.
  • No page chunk has "description":"".
  • In a browser on ru/grilling.html, after hydration the description is still the chapter's, and both og:locale:alternate tags (en_US, es_ES) are present.
  • Tests cover the plugin and check head keys against VitePress's dedupe rule. mise run check passes.

🤖 Generated with Claude Code

The VitePress client rewrote meta description to the empty frontmatter
description, falling back to the site's, so every rendered page showed
the same English text. A markdown-it plugin now writes the description
into the frontmatter; the table of contents takes its locale home's.

Also give each og:locale:alternate tag an id, since VitePress kept only
one meta per key.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@mokevnin
mokevnin merged commit 073181a into main Nov 21, 2026
4 checks passed
@mokevnin
mokevnin deleted the fix/seo-descriptions branch November 21, 2026 15:06
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant